<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html lang="en">
<head>
<meta name="copyright" content="Copyright (c) IBM Corporation and others 2011. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="STYLESHEET" href="../../book.css" charset="ISO-8859-1" type="text/css">
<title>Incompatibilities between Eclipse 3.7 and 4.2</title>
</head>

<body>

<h1>Incompatibilities between Eclipse 3.7 and 4.2</h1>

<p>
  Eclipse changed in incompatible ways between 3.7 and 4.2 in ways that affect 
  plug-ins. The following entries describe the areas that changed and provide 
  instructions for migrating 3.7 plug-ins to 4.2. Note that you only need to look 
  here if you are experiencing problems running your 3.7 plug-in on 4.2.
</p>

<ol>
	<li><a href="#runtime-auth">Platform keyring implementation removed</a></li>
	<li><a href="#2x-compatibility-removed">Compatibility bundles for Eclipse 1.0-2.1 removed</a></li>
	<li><a href="#help-appserver">Bundle org.eclipse.help.appserver removed</a></li>
	<li><a href="#update-manager">Update Manager bundles removed</a></li>
	<li><a href="#presentationAPI">Presentation API no longer functional</a></li>
	<li><a href="#window-advisor">Workbench window advisor can no longer customize window creation</a></li>
	<li><a href="#jetty">Servlet 3.0 and Jetty 8</a></li>
</ol>

<hr>
<!-- ############################################## -->
<h2>1. <a name="runtime-auth">Platform keyring implementation removed</a></h2>
<p><strong>What is affected:</strong> Clients that call the following methods for
storing and retrieving passwords in the platform keyring file:</p>
<ul>
<li>Platform#addAuthorizationInfo</li>
<li>Platform#getAuthorizationInfo</li>
<li>Platform#flushAuthorizationInfo</li>
<li>Platform#addProtectionSpace</li>
<li>Platform#getProtectionSpace</li>
</ul>

<p><strong>Description:</strong> These APIs were deprecated and superseded by new
API in the <tt>org.eclipse.equinox.security.storage</tt> package in Eclipse 3.4.
These APIs made use of a custom encryption algorithm that caused problems
for organizations distributing and exporting Eclipse-based products. The system was
also inherently flawed due to relying on a password supplied on the command line
that users never set. In Eclipse 4.2 this problematic implementation has been removed.
The API remains in place and will log an exception when used.
</p>
<p><strong>Action required:</strong> Clients that call these methods should instead
use the corresponding Equinox security APIs for storing authentication information instead.
Refer to the deprecation comment on each method for precise migration instructions.
</p>
<!-- ############################################## -->
<h2>2. <a name="2x-compatibility-removed">Compatibility bundles for Eclipse 1.0-2.1 removed</a></h2>
<p><strong>What is affected:</strong>Bundles built for Eclipse 1.0 to 2.1 that have
not been compiled in Eclipse 3.0 or later. Also, any bundle or feature that requires
or includes a removed bundle.</p>
<p><strong>Description:</strong> The following bundles provided implementation
of compatibility mechanisms to support bundles compiled against Eclipse prior to version 3.0.
These bundles have not contained any API since the 3.0 release, and no API is
changed or removed as a consequence of these bundles being removed.</p>
<ul>
<li>org.eclipse.core.boot</li>
<li>org.eclipse.ui.presentations.r21</li>
<li>org.eclipse.ui.workbench.compatibility</li>
</ul>

<p><strong>Action required:</strong> Clients with a bundle or feature including
or requiring any of these bundles should remove the requirement.
</p>
<!-- ############################################## -->
<h2>3. <a name="help-appserver">Bundle org.eclipse.help.appserver removed</a></h2>
<p><strong>What is affected:</strong>Any bundle or feature that requires or includes 
the bundle <tt>org.eclipse.help.appserver</tt>.
</p>
<p><strong>Description:</strong> This bundle provided implementation of a Tomcat-based
web server application for the Eclipse help system. This was replaced in Eclipse 3.3 with
a Jetty-based application server. This bundle defines no API and has been unused
in the Eclipse platform for many releases.
</p>
<p><strong>Action required:</strong> Clients with a bundle or feature including
or requiring the bundle <tt>org.eclipse.help.appserver</tt> should remove the requirement.
</p>
<!-- ############################################## -->
<h2>4. <a name="update-manager">Update Manager bundles removed</a></h2>
<p><strong>What is affected:</strong> Clients that rely on the provisional API
or implementation found in the following bundles:</p>
<ul>
<li>org.eclipse.update.core</li>
<li>org.eclipse.update.core.win32</li>
<li>org.eclipse.update.scheduler</li>
<li>org.eclipse.update.ui</li>
</ul>

<p><strong>Description:</strong> These provisional APIs were deprecated and 
superseded by new API provided by Equinox p2 in Eclipse 3.4. These bundles have
been removed from the Eclipse SDK in 4.2, but remain available and fully compatible
with 4.2 should any application or product require them.
</p>
<p><strong>Action required:</strong> Clients that rely on the provisional
API or implementation in these bundles should migrate to the functionality and API
provided by Equinox p2. Alternatively, products can install these bundles from the
Eclipse 3.8 repository and they will continue to function in Eclipse 4.2-based applications.
</p>

<!-- ############################################## -->
<h2>5. <a name="presentationAPI">Presentation API no longer functional</a></h2>
<p><strong>What is affected:</strong> Clients that the used the API in package
<tt>org.eclipse.ui.presentations</tt>, or the <tt>org.eclipse.ui.presentationFactories</tt>
extension point.
</p>
<p><strong>Description:</strong> The workbench <i>presentation API</i> allowed
plug-ins to override certain aspects of the workbench appearance, such as the shape
of view and editor tabs. This mechanism is fundamentally incompatible with the pluggable
rendering and declarative styling systems in Eclipse 4.2, which offer applications complete
control over all aspects of the workbench layout and style. 
</p>
<p><strong>Action required:</strong> Using the presentation API
and extension point to customize the workbench appearance will no longer have any
effect. Clients are encouraged to try out the provisional new API in Eclipse 4.2 for
performing equivalent workbench customization. Complete rendering control can
be achieved by supplying an <tt>org.eclipse.e4.ui.workbench.IPresentationEngine</tt>.
Customization of fonts, spacing, and color can be achieved by supplying custom
CSS style sheets via the <tt>org.eclipse.e4.ui.css.swt.theme</tt> extension point.
For more details, see the <a href="http://wiki.eclipse.org/Eclipse4/RCP/CSS">Eclipse 4 CSS Styling</a> wiki page.
</p>

<!-- ############################################## -->
<h2>6. <a name="window-advisor">Workbench window advisor can no longer customize window creation</a></h2>
<p><strong>What is affected:</strong> Clients that implemented the API methods
<tt>createWindowContents</tt> or <tt>createEmptyWindowContents</tt> on subclasses
of <tt>org.eclipse.ui.application.WorkbenchWindowAdvisor</tt>.
</p>
<p><strong>Description:</strong> The workbench window advisor provided these methods
for rich client applications to build customized workbench windows. This is achieved in 
Eclipse 4.2 by defining a customized application model, so these workbench window
advisor methods are no longer used. Client implementations of these methods will
no longer be called, and therefore no longer have any effect.
</p>
<p><strong>Action required:</strong> Clients that still customize many aspects
of the workbench window layout by invoking the <tt>set*</tt> methods on
<tt>org.eclipse.ui.application.IWorkbenchWindowConfigurer</tt>. Complete customization
of the workbench window elements can be achieved by defining a custom workbench
model for the application.
For more details, see the <a href="http://wiki.eclipse.org/Eclipse4/RCP#Contributing_to_the_Model">Eclipse 4 workbench model</a> wiki page.
</p>

<!-- ############################################## -->
<h2>7. <a name="jetty">Servlet 3.0 and Jetty 8</a></h2>
<p><strong>What is affected:</strong> Clients that relied on the Servlet and Jetty implementations provided
by the platform.
</p>
<p><strong>Description:</strong>
For the Juno release, Equinox will no longer support the use of older
Jetty implementations and we are no longer shipping Jetty 6.  The
Equinox HTTP service implementation will no longer work with the
Servlet 2.5 and JSP 2.1 APIs.  Also note that the 
Jasper and expresson language implementation bundles
have changed in order to support the Servlet 3.0 and JSP 2.2 
specifications.  The following bundles have been removed:</p>
<ul>
  <li>org.apache.jasper</li>
  <li>org.apache.commons.el</li>
  <li>org.mortbay.jetty.server</li>
  <li>org.mortbay.jetty.util</li>
</ul>
<p>These have been replaced with the following to support Servlet 3.0 and JSP 2.2:</p>
<ul>
  <li>org.eclipse.jetty.continuation</li>
  <li>org.eclipse.jetty.http</li>
  <li>org.eclipse.jetty.io</li>
  <li>org.eclipse.jetty.security</li>
  <li>org.eclipse.jetty.server</li>
  <li>org.eclipse.jetty.servlet</li>
  <li>org.eclipse.jetty.util</li>
  <li>javax.el</li>
  <li>org.apache.jasper.glassfish</li>
  <li>com.sun.el</li>
</ul>

<p><strong>Action required:</strong> Clients relying on old Servlet and JSP specifications,
or directly requiring old Jetty 6 packages and bundles, must migrate to the new Servlet 3.0 specification,
and Jetty 8.
</p>

</body>
</html>